home *** CD-ROM | disk | FTP | other *** search
/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / c / keymap.exe / README < prev   
Text File  |  1993-03-28  |  5KB  |  125 lines
  1. KEYMAP.COM
  2. ==========
  3.  
  4. This is a "quick and dirty" utility I threw together to solve what, for me,
  5. has been a very iritating problem:  lack of a consistent, comprehensive
  6. C header file for defining keystrokes on an IBM PC.
  7.  
  8. The idea is simple:  define, for each scan code, a set of mnemonic symbols
  9. which may be used as macro definitions when refering to keys by scan code
  10. in C programs.  To make it even more simple all extended scan codes are
  11. mapped into the same table by increasing their value by 126 (dec).
  12.  
  13. This means that for ANY key stroke, a unique code is returned which will
  14. fit easily into an integer and may be used to identify the key which was
  15. pressed by means of a simple integer test.
  16.  
  17. The purpose for this utility is to aid in constructing the keader file by
  18. actually allowing the user to press each key on the keyboard and assign
  19. one or more mnemonic names to it.  These are then written to a file as
  20. standard C language #define statements.
  21.  
  22. This approach makes it easier to be consistent and symetrical in assigning
  23. names and helps illustrate which keys are, in fact, mapped together.  For
  24. instance CTRL-C and CTRL-BREAK which are the same scan code.  It also allows 
  25. the programmer to take advantage of any existing header files s/he may
  26. already have.
  27.  
  28. I, of course, used this utility to construct my own header file which I have
  29. included in this archive.  It is called KEYS.H.  I also included the source
  30. code to keymap (keymap.c) which was compiled using Borland Turbo C 2.0.  This
  31. may come in handy for someone who likes the concept but wants to use a
  32. different key-coding scheme; all you need to do is modify the keyboard
  33. reading logic to return your scan codes.
  34.  
  35. Anyway, I hope you find it useful.
  36.  
  37.  
  38. USING THE PROGRAM
  39. =================
  40.  
  41. The program is straight forward but admittedly terse.  It insists on two
  42. arguments: the input file name containing any exisitng define statements and
  43. the output file name to which the program will write it's definitions when
  44. it exits.
  45.  
  46. The input file must be specified and must exist (though it may be empty).
  47. It may contain zero or more statements of the form:
  48.  
  49. #define    SYMBOL    HEXVALUE
  50.  
  51. for example:
  52.  
  53. #define    ESC_KEY   0x1B
  54.  
  55. Any lines of a different format except blank lines and lines consisting of
  56. all whitespace may confuse the program.  Sorry, but the values in the
  57. input file must be in the C language hexidecimal format.  If you wish to
  58. use an existing header file as input to this program and your values are
  59. not in hex you will need to change the %0X format in the fscanf() call to
  60. some other format specifier.  You may also wish to change the fprintf to
  61. match though it won't make any difference to your C preprocessor.
  62.  
  63. These lines are parsed and a table of scan codes is built from them.  The
  64. scan code is the index into the table array and each entry in the table will
  65. point to a list of zero or more "key names" for that scan code.
  66.  
  67. The output file need not exist and if it does will be overwritten.  The same
  68. file may be specified for both input and output file.  In this case the table
  69. is read from the file, Definitions are added, and the file is rewritten.
  70. This is how I use the utility.
  71.  
  72. If you make a mistake when entering names you may exit the program, fix the
  73. mistake in the output file using an ASCII text editor, and re-enter the
  74. program  to continue.  The program contains no support for directly editing
  75. or deleting names after they have been entered.
  76.  
  77. To start the program type:
  78.  
  79.         keymap <infile> <outfile>
  80.  
  81. and press enter.
  82.  
  83.  
  84. KEYMAP reads the specified input file and then displays the prompt:
  85.  
  86.         Press a key:
  87.  
  88. At this point you may depress a single keystroke.  The program will determine
  89. the scan code, display any existing names assigned to it and then display the
  90. prompt:
  91.  
  92. #define 
  93.  
  94. enter a mnemonic name for the key (31 characters max) and press <enter>.
  95.  
  96. The name will be added to the list and another #define prompt will be shown.
  97. You may enter as many names for the scan code as you wish.  When you have
  98. entered all of them simply press <enter> by itself at the #define prompt and
  99. you will be taken back to the "Press a key:" prompt.
  100.  
  101. You may define as many key names as you wish.  When you are finished simply
  102. press the ESCAPE key at the "Press a key:" prompt.  The program will write
  103. the new header file to the output file and return to DOS.
  104.  
  105. The perceptive reader will observe that it is impossible to map the ESCAPE
  106. key itself with this program.  This is true.  You will have to do that
  107. particular key by hand...sue me!
  108.  
  109. Beware of pressing CTRL-C or CTRL-BREAK from the "#define" prompt as that
  110. will cause premature program termination which will result in the loss of
  111. all definitions added during the current session.  It is also likely to be
  112. embarassing.
  113.  
  114. This program is not copyrighted, is guaranteed to contain bugs and is not 
  115. supported by the author or anyone else I know of so you're on your own.  
  116. However, any feedback (or just pats on the back) would be well received.  
  117. I can be reached via compuserve c/o: 
  118.  
  119.         ORIGIN Technology in Business - 70674,616
  120.  
  121.  
  122. Hope you enjoy it.
  123.  
  124. John Hardegree, March 28, 1993.
  125.